<html><!-- #BeginTemplate "/Templates/maintemplate.dwt" -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<!-- #BeginEditable "doctitle" --> 
<title>JEP - Java Math Expression Parser</title>
<!-- #EndEditable --> 
<link rel="stylesheet" type="text/css" href="main.css" title="style1">
</head>

<body>



<!-- NAVIGATION ---------------------------------------------------- -->
<div id="navcontainer"> 
  <ul>
    <li><a href="../javadoc/index.html" target="_blank">JavaDoc <img src="img/new-window-icon.gif" width="15" height="11"></a></li>
  </ul>
  <h1>JEP</h1>
  <ul>
    <li><a href="index.html">Basic Usage</a></li>
    <li><a href="variables.html">Variables</a></li>
    <li><a href="types.html">Data types</a></li>
    <li><a href="operators.html">Operators</a></li>
    <li><a href="functions.html">Functions</a></li>
    <li><a href="advanced.html">Advanced Features</a></li>
    <li><a href="grammar.html">Grammar</a></li>
    <li><a href="faq.html">FAQ</a></li>
    <li><a href="version.html">Version History</a></li>
  </ul>
  <h1>Extensions</h1>
  <ul>
    <li><a href="extensions/index.html">Overview</a></li>
    <li><a href="extensions/xjep.html">XJep</a></li>
    <li><a href="extensions/djep.html">Differentiation</a></li>
    <li><a href="extensions/vectorjep.html">Vectors and Matrices</a></li>
    <li><a href="extensions/groupjep.html">Groups</a></li>
    <li><a href="extensions/version.html">Version History</a></li>
  </ul>
</div>



<div id="centercontent">
<!-- CENTER CONTENT -------------------------------------------------- -->
<!-- #BeginEditable "Text" --> 
  <h1><a name="top"></a>Variables</h1>
    <ul>
    <li><a href="#basics">Basics</a></li>
    <li><a href="#allowingundeclared">Allowing undeclared variables</a></li>
    <li><a href="#obtainingalist">Obtaining a list of variables</a></li>
    <li><a href="#assignment">Assignment</a></li>
    <li><a href="#observers">Observers for variables</a></li>
  </ul>
  <h2><a name="basics"></a>Basics</h2>
  <p>Two options are available in working with variables</p>
  <ol>
    <li><b>Do not allow undeclared variables (default):</b> In this case it is 
      necessary to add a variable before parsing an expression with that variable 
      in it. This is accomplished with the <a href="../javadoc/org/nfunk/jep/JEP.html#addVariable(java.lang.String, java.lang.Object)">addVariable</a> 
      method.</li>
    <li><b>Allow undeclared variables:</b> If you allow undeclared variables, 
      they are automatically added to the symbol table while parsing an expression.</li>
  </ol>
  <p>After an expression has been parsed, variable values can be updated using 
    either <a href="../javadoc/org/nfunk/jep/JEP.html#addVariable(java.lang.String, java.lang.Object)">addVariable</a> 
    or <a href="../javadoc/org/nfunk/jep/JEP.html#setVarValue(java.lang.String, java.lang.Object)">setVarValue</a>. 
    This allows repeated evaluation of an expression with different variable values.</p>
  <p>The value of a variable can be queried using <a href="../javadoc/org/nfunk/jep/JEP.html#getVarValue(java.lang.String)">getVarValue</a> 
    method. A further method <a href="../javadoc/org/nfunk/jep/JEP.html#getVar(java.lang.String)">getVar</a> 
    returns an object representing the variable. </p>
  <p>Variables can be constants which cannot have their values changed. To add 
    a new constant use <a href="../javadoc/org/nfunk/jep/JEP.html#addConstant(java.lang.String, java.lang.Object)">addConstant</a> 
    to add a mutable variable use&nbsp;<a href="../javadoc/org/nfunk/jep/JEP.html#addVariable(java.lang.String, java.lang.Object)">addVariable</a>.</p>
  <p>The SymbolTable class stores objects representing variables rather than just 
    their values. The <a href="../javadoc/org/nfunk/jep/SymbolTable.html#get(java.lang.Object)">get</a> 
    and <a href="../javadoc/org/nfunk/jep/SymbolTable.html#put(java.lang.Object, java.lang.Object)">put</a> 
    methods of this class are deprecated. This results in a slight speed up during 
    evaluation.<br>
  </p>
  <!-- #BeginLibraryItem "/Library/top bar.lbi" -->
<div class="topbar"><a href="#top"><img src="img/top.gif" width="38" height="15" name="top"></a></div>
<!-- #EndLibraryItem --> 
  <h2><a name="allowingundeclared"></a>Allowing undeclared variables</h2>
  <p>To enable parsing of undeclared variables, use <a href="../javadoc/org/nfunk/jep/JEP.html#setAllowUndeclared(boolean)" target="_blank">setAllowUndeclared(true)</a>. 
    The default setting is false (undeclared variables are not allowed).</p>
  <p>If you do not know what variable names may occur in the expression before 
    parsing it, you can use <code>setAllowUndeclared(true)</code>. With this option 
    enabled, it is not necessary to add variables to the parser before parsing 
    an expression. If a new variable is found while parsing, it is automatically 
    added to the symbol table. See <a href="#obtainingalist">Obtaining a list 
    of variables</a> to read about how to access these variables.</p>
  <!-- #BeginLibraryItem "/Library/top bar.lbi" -->
<div class="topbar"><a href="#top"><img src="img/top.gif" width="38" height="15" name="top"></a></div>
<!-- #EndLibraryItem --> 
  <h2><a name="obtainingalist"></a>Obtaining a list of variables</h2>
  <p>While parsing an expression with undeclared variables allowed, a list of 
    all the variables and constants that have been added to the parser, can be 
    obtained with the <a href="../javadoc/org/nfunk/jep/JEP.html#getSymbolTable()" target="_blank">getSymbolTable</a> 
    method. This method is most useful when the undeclared variables option is 
    enabled. The return value is a SymbolTable object. Note that SymbolTable extends 
    Hashtable.</p>
  <!-- #BeginLibraryItem "/Library/top bar.lbi" -->
<div class="topbar"><a href="#top"><img src="img/top.gif" width="38" height="15" name="top"></a></div>
<!-- #EndLibraryItem --> 
  <h2><a name="assignment"></a>Assignment</h2>
  <p> Assignment allows the values of variables to be set by using the <tt>=</tt> 
    operator in equations so it is possible to do something like <tt>x=3</tt> 
    then <tt>y=x^2</tt> and <tt>y</tt> will have the value 9. Assignment can be 
    used with the standard JEP package, there is no need to use any of the packages 
    in the org.lsmp.djep tree. To switch on assignment facilities the <a href="../javadoc/org/nfunk/jep/JEP.html#setAllowAssignment(boolean)">setAllowAssignment</a> 
    method of the main JEP object should be called. </p>
  <pre>// standard initialisation<br>JEP j = new JEP();<br>j.addStandardConstants();<br>j.addStandardFunctions();<br>j.addComplex();<br>j.setAllowUndeclared(true);<br>j.setImplicitMul(true);<br><br>// switch assignment facilities on<br>j.setAllowAssignment(true);<br><br>// parse assignment equations<br>j.parseExpression("x=3");<br>// evaluate it - no need to save the value returned<br>j.getValueAsObject();<br>// parse a second equation<br>j.parseExpression("y=2");<br>j.getValueAsObject();<br><br>// an equation involving above variables<br>j.parseExpression("x^y");<br>Object val3 = j.getValueAsObject();<br>System.out.println("Value is " + val3);</pre>
    <!-- #BeginLibraryItem "/Library/top bar.lbi" -->
<div class="topbar"><a href="#top"><img src="img/top.gif" width="38" height="15" name="top"></a></div>
<!-- #EndLibraryItem --> 
  <h2><a name="observers"></a>Observers for variables</h2>
  <p> Both SymbolTable and Variable implement the Observer/Observable pattern. 
    This allows objects to be informed whenever a new variable is created or when 
    its value has been changed. An example of use is 
  <pre>
public class MyObserver implements Observer
{
    public void initialise()
    {
        SymbolTable st = j.getSymbolTable();
        st.addObserver(this);
        st.addObserverToExistingVariables(this);
    }

    public void update(Observable arg0, Object arg1)
    {
        if(arg0 instanceof Variable)
            println("Var changed: " + arg0);
        else if(arg0 instanceof SymbolTable.StObservable)
        {
            println("New var: "+arg1);

            // This line is vital to ensure that 
            // any new variable created will be observed. 
            ((Variable) arg1).addObserver(this);
        }
    }
}
</pre>

  <!-- #BeginLibraryItem "/Library/top bar.lbi" -->
<div class="topbar"><a href="#top"><img src="img/top.gif" width="38" height="15" name="top"></a></div>
<!-- #EndLibraryItem --> 
  <!-- #EndEditable -->




<!-- FOOTER ---------------------------------------------------------- -->
<div id="footer">
<a href="http://sourceforge.net/tracker/?func=add&group_id=24711&atid=382402">Report bugs / documentation errors</a><br/>
<br/>
&copy; 2006 <a href="http://www.singularsys.com" target="_blank">Singular Systems</a>
</div>
</div> <!-- centercontent -->

</body>
<!-- #EndTemplate --></html>
